🐝 Use API

Camomilla comes with many api endpoint builded with Django Rest Framework.

To use the endpoints you need to add the handler to the project urls.py

# <project_name>/urls.py
urlpatterns += path('api/camomilla/', include('camomilla.urls'))

⚠️ Beware!

Remember that if you use camomilla pages dynamic_pages_urls handler should always be the last handler of your urlpatterns list.

By default every endpoint comes with a full CRUD in the style of django rest framework with some mode feature beaked in.

🧱 Base Classes

If you need to implement your own api, we suggest to use camomilla BaseModelSerializer and BaseModelViewset as the base class of your serializer and viewset respectively.

class MyModelSerializer(BaseModelSerializer):
    class Meta:
        model = MyModel
        fields = "__all__"
        depth = 5

class MyModelViewSet(BaseModelViewset):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer
    permission_classes = (CamomillaBasePermissions,)
    model = MyModel
    search_fields = ["title", "description",]

This will provide to your endpoint all the features of standard camomilla api.

🖲️ The model_api.register decorator

If you need to create a standard api endpoint you can take advantage of model_api register decorator. To use this aproach you need to add the model_api handler to your project urls.py

# <project_name>/urls.py
urlpatterns += path('api/models/', include('camomilla.model_api'))

Then you just need to decorate your model with @model_api.register

from camomilla import model_api

@model_api.register()
class MyModel(models.Model):
    title = models.CharField(max_length=200)
    description = models.TextField(null=True, blank=True)

This will create an api endpoint with url /api/models/my-model with full camomilla api capabilities.

You can also personalize the view or the serializer passing some parameter to the register function:

• base_serializer: The base serializer to use for the model.
• base_viewset: The base viewset to use for the model.
• serializer_meta: The meta class to use for the serializer.
• viewset_attrs: The attributes to add to the viewset.
• filters: The filters to apply to the queryset.

🗂️ List endpoint

URL Structure:

• api/camomilla/<model_name>

Simple Response:

[
    { ... single model data ... }, {}, {}
]

Use Pagination

List api comes with a builtin paginator. The paginated response is disabled by defualt to be compliant with default rest framework lists. If you want a paginated response you need to specify the page size in the request as a GET parameter.

For example, the request /api/camomilla/<model_name>?items=10, will return data splittet 10 elements per page.

Paginated Response:

{
    "items": [
        { ... single model data ... }, {}, {}
    ],
    "paginator": {
        "count": 1, // number of elements
        "page": 1, // current page number
        "has_next": false, // has a next page
        "has_previous": false, // has a previous page
        "pages": 1, // total number of pages
        "page_size": 10 // number of elements per page (depends on items parameter)
    }
}

Use Filtering

List api comes with a builtin filter syntax. You can filter data with GET query parameters using the following sintax:

/api/camomilla/<model_name>?fltr=field_name=value

This syntax can be repeated multiple times.

/api/camomilla/<model_name>?fltr=field_name=value&fltr=field_name=value

In place of field_name you can use any django filter argument (opens new window).

If the value has commas like val1,val2,val3 it will be treated as an array. For example you can filter some model like this:

/api/camomilla/<model_name>?fltr=field_name__in=val1,val2

Use Search

You can also full text search your model with query param search:

/api/camomilla/<model_name>?search=q_string

🗂️ Detail endpoint

Retrieve api just returns model data serialized in a json. The serialization goes through nested objects by default, creating on the fly nested serializers. You can modify this behaviour decreasing the value depth in Serializer Meta for a single serializer or change the default option in camomilla settings.

CAMOMILLA = {
    "MEDIA": {
        "API": {"NESTING_DEPTH": 10 }
    },
}

URL Structure:

• api/camomilla/<model_name>/<primary_key>

Simple Response:

{ ... single model data ... }